All Databases Inside Mac - DAM/Ed/PPC/Slot

DBGetQueryResults

Retrieve and store the results returned by a query

#include <DatabaseAccess.h> Data Access Manager

OSErr DBGetQueryResults( sessID, results, timeout, statusProc,

asyncPB);

long sessID ; specifies a session ID

ResultsRecord * results ; is the results record

long timeout ; specifies the maximum amount of time that

the database extension should wait to receive

results

ProcPtr statusProc ; a pointer to a status routine

DBAsyncParmBlkPtr asyncPB ; a pointer to an asynchronous parameter block.

returns Error Code; 0=no error

The DBGetQueryResults function retrieves the results returned by a query

and places them in memory. If there is sufficient memory available, this

function retrieves all of the results at once. If the DBGetQueryResults

function runs out of memory, it places as much data as possible in memory, up

to the last whole row. You can then make more memory available and call the

DBGetQueryResults function again to retrieve more data.

The DBGetQueryResults function can be used to retrieve the results of any

query, not only queries sent and executed by the DBStartQuery function.

sessID specifies the ID of the session from which you wish to retrieve

results.

results is the results record, which contains handles to the retrieved data.

Results records are described in Getting Query Results in the

section entitled Processing Query Results. You must allocate the

results record data structure and pass this record to the

DBGetQueryResults function. The Data Access Manager

allocates the handles inside the results record. When your application

is finished using the results record, you must deallocate both the

results record and the handles inside the results record.

timeout specifies the value that the DBGetQueryResults function uses for

the timeout parameter each time it calls the DBGetItem function.

The timeout parameter specifies the maximum amount of time that

the database extension should wait to receive results from the data

server before canceling the DBGetItem function. Specify the

timeout parameter in sixtieths of a second. To disable the timeout

feature, set the timeout parameter to the kDBWaitForever constant.

Some database extensions ignore the timeout parameter when you

specify a nonzero value for the asyncPB parameter.

statusProc specifies a pointer to a status routine that you provide. The

DBGetQueryResults function calls your status routine after it

calls the DBGetItem function to retrieve a data item. When it calls

the status routine, the DBGetQueryResults function provides the

result of the DBGetItem function, the data type, data length, number

of decimal places, and flags associated with the data item, and a

pointer to the data item. For status routines see,

Writing a Status Routine for High-Level Functions .

asyncPB If you specify a pointer to an asynchronous parameter block in the

asyncPB parameter, the DBGetQueryResults function calls the

DBGetItem function asynchronously for each data item. As soon as

the DBGetItem function has started execution, it returns control to

your application. Your application must then call the

WaitNextEvent function periodically to allow this asynchronous

routine to run, and it must check the result field of the asynchronous

parameter block to determine when the routine has completed

execution.

Returns: an operating system Error Code.

noErr (0) Query execution successful; no results returned

userCanceledErr (-128) Function cancelled by status routine

rcDBValue (-801) Data available

rcDBError (-802) Error on executing query

rcDBBreak (-804) Function timed out

rcDBExec (-805) Query currently executing

rcDBBadSessID (-806) Session ID is invalid

rcDBAsyncNotSupp (-809) The database extension does not support asynchronous

calls

rcDBPackNotInited (-813) The InitDBPack function has not yet been called

Referenced by (15):